🤖 feat: Agent Plugins install/update UX (managed installs, v1) - #3820

New AgentPluginInstallEntry schema persisted as a 'plugins' section in
~/.mux/config.json via Config's atomic writes. source.ref is the tracking
channel; lockedSha is what runs. Invalid entries are dropped lenient-on-read
(discovery stays the source of truth for what loads).

- Registry moved to standalone ~/.mux/plugins.json: older builds rebuild
  config.json from known fields on save (passthrough only affects schema
  validation), so a downgrade would drop an embedded registry; owning the
  file also lets writes THROW so install rolls back the promoted dir and
  uninstall/update surface persistence failures instead of silently
  succeeding (Q2's own contingency: 'migration to a separate file')
- Traversal safety: plugin-name grammar (shared via
  src/common/utils/agentPluginName.ts) enforced in the registry schema and
  asserted in targetPathFor, so a malformed entry named '.'/'..' can never
  resolve outside the container that uninstall deletes recursively
- Fallback clone: reset the staging dir before the branch-clone fallback
  (fetchExactSha leaves an initialized repo; git clone refuses non-empty)
- Keyboard rule: palette commands Install Agent Plugin… (opens the section
  with the add panel expanded), Check for Plugin Updates (toast + navigate),
  Update All Plugins (applies update-available; moved tags stay manual)
- New tests: registry survives config.json rewrites, traversal names dropped,
  registry-write failure rollback, SHA-fetch-refused fallback (file:// remote
  with uploadpack.allowAnySHA1InWant=false)

- uninstall: stage the tree out (rename to staging) BEFORE the registry
  write; a locked/undeletable tree now fails cleanly with the install fully
  intact, and a failed registry write renames the tree back
- palette 'Install Agent Plugin…': mounted sections subscribe to the intent
  so invoking the command while Settings → Plugins is already open expands
  the add panel (initializer covers the fresh-mount path)
- section: mutation errors are re-asserted after refresh (refresh success
  cleared them); failed uninstall keeps the confirmation open
- palette check/update-all: per-plugin status:'error' entries no longer read
  as 'all up to date' — surface which plugins failed and navigate

- palette 'Uninstall Agent Plugin…' with a managed-plugin select prompt;
  routes through the section's confirmation flow (plugin-data checkbox,
  destructive button) — the palette never uninstalls directly
- pluginsSectionIntents generalized to a typed intent bus (open-add-panel /
  confirm-uninstall / refresh); mounted sections subscribe, unmounted
  sections consume the buffered intent on mount
- 'Update All Plugins' publishes a refresh intent so an already-mounted
  section re-queries instead of showing stale versions/badges
- sourceInput expands ~/-relative local paths (git is spawned without a
  shell, so ~ never expands on its own)

- update: stop the plugin's MCP servers BEFORE the old tree is renamed
  (live servers can lose files mid-swap on POSIX; open handles can fail the
  rename on Windows), and recycle again post-promote so content changed
  behind an unchanged command line still restarts — regression test snapshots
  the installed tree version at each recycle (pre-swap sees v1, post sees v2)
- uninstall: best-effort trash deletion (catch + log + leave for staging
  reclamation) so an undeletable staged tree cannot abort override pruning;
  update's replaced-tree deletion gets the same treatment — regression test
  forces EBUSY and verifies uninstall completes and reinstall works
- palette Update All / Check for Updates: check failures stay in the final
  summary even when other updates succeeded (mixed results toast as errors)
- section: update-check errors live in separate state from list/mutation
  errors, so the concurrent mount refresh can never clear an unreachable-
  remote warning (rendered as its own banner)
- sourceInput: expand ~\-style Windows home paths, not just ~/

- P1 MCP startup race: stopServersWithKeyPrefix records an epoch-stamped
  prefix invalidation; getToolsForWorkspace snapshots the clock before
  reading config and closes matching instances at every publish point
  (fresh start, timed-out retry, mid-stream restart) instead of publishing
  them — an update/uninstall swap during an in-flight startup can no longer
  leave an old-tree server running. Race test gates startServers, swaps
  mid-flight, and asserts the instance is closed, not published
- registry rewrites are raw-preserving: mutations operate on the raw entry
  list (per-element validation on read, matched by name on write), so
  entries/fields from newer builds survive install/update/uninstall on this
  build; lifecycle test seeds an archive-source entry + unknown field
- managed list rows keep registry identity (update/uninstall look up by it);
  manifest-name drift is surfaced in the description instead of breaking
  repair from Settings
- update revalidates the resolved ref kind before cloning (deleted branch
  replaced by same-name tag → clear error, registry untouched)
- palette Check for Plugin Updates publishes a refresh intent so a mounted
  section's badges match the toast
- pinned phone-viewport story variant (Pixel matrix + mobile1 global) for
  the narrow-width row layout

- P1: instances removed by mid-startup invalidation are queued in the
  timed-out retry list at every publish point — the entry is published under
  the unchanged full config signature, so without a retry marker the cached
  path would serve the reduced map and the updated plugin's tools would stay
  unavailable indefinitely; the race test now asserts the subsequent
  getToolsForWorkspace restarts the server from the new tree
- P2: stopServersWithKeyPrefix closes ONLY matching instances, preserving
  the rest of the workspace cache (an unrelated healthy client is no longer
  torn down under a live lease/mid tool call); removed keys go through the
  same retry markers; test covers two servers + a held lease

- P1 uninstall re-invalidation: issue a second stopServersWithKeyPrefix
  AFTER the tree+registry removal (mirroring update's post-promote stop) so
  a startup that snapshotted the new epoch but discovered the plugin before
  the rename cannot keep a server running from the removed tree — test
  asserts the recycle pair observes tree-present then tree-gone
- P1 remove manual useCallback: PluginsSettingsSection handlers are plain
  functions (React Compiler repo); mount/subscription effects key on [api]
  with documented eslint-disable per repo precedent
- P2 nested raw preservation: update patches only owned fields (lockedSha,
  updatedAt, manifest version/description) into the RAW entry instead of
  spreading the Zod-parsed entry — unknown metadata inside source/manifest
  survives downgrade round-trips (tested)
- P2 stale update-check responses: generation counter; only the latest
  check commits updateChecks/checkingUpdates state
- P2 plugin-data staging: when deletion is requested, the data dir is
  staged out BEFORE the registry commit; failure aborts the uninstall with
  the row intact so the cleanup can be retried (tested), rollback restores
  both tree and data on registry-write failure

- Update All: moved tags join the final summary ('Tag moved for X — review
  in Settings → Plugins') and taint the toast; tag-moved-only results no
  longer report 'All plugins are up to date'
- Update All: the refresh intent publishes before any early return, so a
  mounted section picks up newly discovered moved tags / check errors even
  when no branch update applied; tag-moved / check-failure outcomes also
  navigate to the section

uninstall runs the post-commit MCP invalidation BEFORE override pruning:
pruneWorkspaceOverrides can throw from getAllWorkspaceMetadata (outside its
per-workspace catch), and a pruning failure must not skip the invalidation
that catches servers started from the removed tree mid-uninstall (test:
metadata enumeration rejects → both stops ran, uninstall committed)

- refresh() gets the same request-generation guard as checkForUpdates: an
  older overlapping list response can no longer resurrect removed rows or
  stale versions over a newer refresh
- uninstall enumerates its override-pruning targets (workspace metadata)
  BEFORE committing anything: enumeration is the only pruning step that can
  fail wholesale, and post-commit it would strand stale enabled-server
  overrides with no Settings row to retry from (reinstall reuses the same
  instance ID and would silently re-enable servers); per-workspace pruning
  stays best-effort post-commit (test: enumeration failure aborts fully
  intact with zero stops, retry completes with both invalidations)

failed per-workspace override prunes persist a retryable tombstone
(pendingOverridePrunes in the plugins.json envelope): retried on section
open (list), and a reinstall of the same name is hard-gated on the pending
prune for its instance-ID prefix — retry-then-refuse, so a stale
enabledServers key can never silently re-enable a reinstalled plugin's
server. Test: unavailable checkout → uninstall commits with tombstone,
reinstall refuses; checkout recovers → override pruned, tombstone cleared,
reinstall succeeds

- P1: retryPendingOverridePrunes runs its read-modify-write under the
  exclusive mutation queue — a section-open retry can no longer clobber a
  concurrent install/update/uninstall with its stale registry snapshot
  (race test: gated prune during list + concurrent install → entry survives,
  tombstone cleared)
- P2: the uninstall COMMIT write carries a pessimistic tombstone for every
  workspace to prune; the post-prune write only shrinks it (best-effort),
  so losing that write leaves the safe over-broad record instead of no
  record (test: prune + shrink-write both fail → tombstone durable,
  reinstall gated)
- P2: tombstone retries reconcile workspace IDs against current metadata
  and drop deleted workspaces — a permanently-missing checkout can no
  longer block reinstall forever (test: dead-ID tombstone → reinstall
  succeeds, tombstone retired)

- WorkspaceMcpOverridesService.removeOverridesFile checks the rm exit code
  and throws: setOverridesForWorkspace must reject when clearing overrides
  fails, or the tombstone machinery would classify the prune as successful
  while the stale enabledServers key survives
- tombstone rewrites are raw-preserving: unrecognized tombstone variants
  pass through verbatim and recognized items keep unknown fields when their
  workspaceIds shrink (test: future variant + extra field survive a full
  uninstall cycle)
- the post-uninstall tombstone shrink re-reads the registry STRICT inside a
  try/catch: a lenient read degrading transient corruption to an empty
  document would have rewritten plugins.json with an empty plugin list; on
  failure the pessimistic commit-write tombstone simply stays

- Consent preview now resolves symlinked skill dirs with allowMissing
  containment (matching runtime assertSkillDirValid), so escaping
  symlinks surface a warning instead of hiding behind ENOENT while
  in-root symlinked skills are disclosed.
- Plugin location/source lines wrap with break-all so max-length
  separator-free names cannot overflow the card at phone widths;
  pinned phone story covers a 64-char name with a scroll-width
  assertion.

Stale Workspace MCP dialog snapshots could restore plugin:<instanceId>:
override keys that an uninstall had just pruned, silently re-enabling a
reinstalled plugin's MCP server.

- workspace.mcp.get now returns { overrides, revision } where revision
  is a content hash of the normalized overrides.
- workspace.mcp.set requires expectedRevision and rejects with a
  conflict error when the stored overrides changed since that read;
  saves are serialized through a write queue so check-and-set is atomic.
- WorkspaceMCPModal passes the loaded snapshot's revision on save, so a
  stale save surfaces 'settings changed while this dialog was open'
  instead of clobbering the prune.
- The uninstaller's override prune passes expectedRevision too and
  re-reads + re-filters on conflict (bounded retries), so a concurrent
  dialog save cannot interleave with the prune's read-modify-write.

An await separated the final prefix-invalidation epoch scan from cache
publication. A stopServersWithKeyPrefix continuation scheduled into that
microtask yield records its epoch AFTER the scan checked it and scans
the published map BEFORE workspaceServers.set runs — both mechanisms
miss, and a server started from a removed/replaced plugin tree stays
alive without a retry marker.

closeInvalidatedInstancesThenPublish now re-scans until the invalidation
clock is stable across a full scan and invokes the publish callback
synchronously in the same continuation as the final clock check. Any
invalidation landing after that check runs its own published-map scan
strictly after publication (single-threaded), so it sees the entry and
closes matching instances. Applied at all three publication sites (miss
path, cached retry path, deferred restart path).

Regression test interleaves stopServersWithKeyPrefix into the exact
yield window via a one-shot instances-map iterator hook that queues a
microtask; it fails on the previous code (stale instance published,
close never called) and passes now.